Searches a volume’s catalog file using a set of search criteria that you specify. It builds a list of all files or directories that meet your specifications.

OSErr PBCatSearchAsync (
    CSParamPtr paramBlock
);

paramBlock

A pointer to a csParam variant of an HFS parameter block.

function result

A result code.

DISCUSSION

The relevant fields of the parameter block are:

• ioCompletion

  On input, a pointer to a completion function.

• ioResult

  On output, the result code of the function.

• ioNamePtr

  On input, a pointer to a pathname.

• ioVRefNum

  On input, a volume specification for the volume to search.

• ioMatchPtr

  On input, a pointer to an array of matches. On return, a pointer to an array of FSSpec structures identifying the files and directories that match the criteria.

• ioReqMatchCount

  On input, the maximum match count.

• ioActMatchCount

  On output, the actual match count.

• ioSearchBits

  On input, enable bits for fields in criteria structures.

• ioSearchInfo1

  On input, the values and lower bounds.

• ioSearchInfo2

  On input, the masks and upper bounds.

• ioSearchTime

  On input, the maximum allowed search time.

• ioCatPosition

  The current catalog position.

• ioOptBuffer

  On input, a pointer to optional read buffer.

• ioOptBufSize

  On input, the length of optional read buffer.

The PBCatSearchAsync function searches the volume you specify for files or directories that match two coordinated sets of selection criteria.

If the catalog file changes between two timed calls to PBCatSearchAsync (that is, when you are using ioSearchTime and ioCatPosition to search a volume in segments and the catalog file changes between searches), PBCatSearchAsync returns a result code of catChangedErr and no matches. Depending on what has changed on the volume, ioCatPosition might be invalid, most likely by a few entries in one direction or another. You can continue the search, but you risk either skipping some entries or reading some twice.

When PBCatSearchAsync has searched the entire volume, it returns eofErr. If it exits because it either spends the maximum time allowed by ioSearchTime or finds the maximum number of matches allowed by ioReqMatchCount, it returns noErr. You can specify a value of 0 in the ioSearchTime field to indicate that no time limit is to be enforced.

Not all volumes support the PBCatSearchAsync function. Before you call PBCatSearchAsync to search a particular volume, you should call the PBHGetVolParmsAsync function to determine whether that volume supports PBCatSearchAsync.

Even though AFP volumes support PBCatSearchAsync, they do not support all of its features that are available on local volumes. These restrictions apply to AFP volumes:

• AFP volumes do not use the ioSearchTime field. Current versions of the AppleShare server software search for 1 second or until 4 matches are found. The AppleShare workstation software keeps requesting the appropriate number of matches until the server returns either the number specified in the ioReqMatchCount field or an error.
• AFP volumes do not support both logical and physical fork lengths. If you request a search using the length of a fork, the actual minimum length used is the smallest of the values in the logical and physical fields of the ioSearchInfo1 structure and the actual maximum length used is the largest of the values in the logical and physical fields of the ioSearchInfo2 structure.
• The fsSBNegate bit of the ioSearchBits field is ignored during searches of remote volumes that support AFP version 2.1.
• If the AFP server returns afpCatalogChanged, the catalog position structure returned to your application (in the ioCatPosition field) is the same one you passed to PBCatSearchAsync. You should clear the initialize field of that structure to restart the search from the beginning.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)